/**
 * 构建 URL 查询字符串
 * @param {Object} params - 待转换的参数对象（键值对形式）
 * @param {Object} [options={}] - 配置选项
 * @param {boolean} [options.ignoreEmpty=false] - 是否忽略空值（''、null、undefined）
 * @param {boolean} [options.encode=true] - 是否对参数值进行 URL 编码（处理中文、特殊字符）
 * @returns {string} 标准的 URL 查询字符串（开头无"?"，可直接拼接在 URL 后）
 *
 * @example
 * // 基础使用
 * buildQueryString({ keyword: "手机", page: 1, pageSize: 10 })
 * // 输出: "keyword=%E6%89%8B%E6%9C%BA&page=1&pageSize=10"
 *
 * @example
 * // 处理数组
 * buildQueryString({ ids: [1, 2, 3], sort: ["price", "time"] })
 * // 输出: "ids=1&ids=2&ids=3&sort=price&sort=time"
 *
 * @example
 * // 忽略空值
 * buildQueryString({ keyword: "", page: null, pageSize: 10 }, { ignoreEmpty: true })
 * // 输出: "pageSize=10"
 */
export function buildQueryString(params = {}, options = {}) {
    // 默认配置：忽略空值、自动 URL 编码
    const {
        ignoreEmpty = true, encode = true
    } = options;

    // 存储最终的键值对数组（格式：["key=value", "key2=value2"]）
    const queryPairs = [];

    // 遍历参数对象的每一个键值对
    Object.entries(params).forEach(([key, value]) => {
        // 1. 过滤无效键（键为null/undefined/空字符串时跳过）
        if (!key || key.trim() === '') return;

        // 2. 处理值的不同类型
        let processedValues;
        if (Array.isArray(value)) {
            // 数组类型：拆解为多个同键参数（如 ids=[1,2] → ids=1&ids=2）
            processedValues = value;
        } else {
            // 非数组类型：包装为数组，统一后续处理逻辑
            processedValues = [value];
        }

        // 3. 遍历处理后的值，生成键值对
        processedValues.forEach(val => {
            // 根据配置决定是否忽略空值
            if (ignoreEmpty) {
                // 空值判定：undefined、null、空字符串、纯空格字符串
                const isEmpty =
                    val === undefined ||
                    val === null ||
                    (typeof val === 'string' && val.trim() === '') ||
                    (typeof val === 'number' && isNaN(val)); // 排除 NaN
                if (isEmpty) return;
            }

            // 4. 格式化值（布尔值转字符串，其他类型直接转字符串）
            let formattedVal;
            if (typeof val === 'boolean') {
                formattedVal = val ? 'true' : 'false'; // 布尔值统一为小写字符串
            } else {
                formattedVal = String(val); // 其他类型转为字符串（如数字 1 → "1"）
            }

            // 5. 根据配置决定是否 URL 编码（处理中文、特殊字符如 &、= 等）
            const finalKey = encode ? encodeURIComponent(key) : key;
            const finalVal = encode ? encodeURIComponent(formattedVal) : formattedVal;

            // 6. 添加到键值对数组
            queryPairs.push(`${finalKey}=${finalVal}`);
        });
    });

    // 7. 拼接所有键值对，返回最终查询字符串
    return queryPairs.join('&');
}